v7 to v9 config migration script #669

so-schen · 2025-05-22T06:57:58Z

Requirements

We need devops team to package this migrate-config python script to rpc_node and supra version 9 docker image for mainnet, so that operator do not need to install locally @darpan-supraoracles
We need to have snapshot bucket created for mainnet rpc and validator

        if is_validator; then
            bucket_name="mainnet-validator-snapshot"
        elif is_rpc; then
            bucket_name="mainnet-snapshot"

Note that aws access key may need to be updated in script

This script support --assume-yes option to apply default migration values without prompting, it is most common use case for regular nodes, so that it is possible to batch processing config migration for our foundation nodes.

IMPORTANT note for DEVOPS
But for specially denoted nodes (i.e. archives, snapshot uploaders), use interactive prompt:
Do not use --assume-yes for these nodes, because the enable_snapshots and enable_pruning should retain original value instead of using the default.
Run the script in interactive prompt and confirm each update, and also check final output of migration .

Operator should run interactively and follow the guide from the prompts. Operator should not run db migration, instead they should use snapshot sync to restart a node using v9 image

v7-v9 config migration docs

Install the config migration script

from root dir of repo, you can install it like below
pip install node_management/config_migration

Usage

$ migrate-config --help
Usage: migrate-config [OPTIONS] COMMAND [ARGS]...

  Migration CLI for Supra configs.

Options:
  --help  Show this message and exit.

Commands:
  rpc  Migrate RPC config.
  smr  Migrate SMR config.

$ migrate-config rpc  --help
Usage: migrate-config rpc [OPTIONS]

  Migrate RPC config.

Options:
  -p, --migrate-path [v7-v9]  Migration path (choices: v7-v9)  [required]
  -f, --from-file PATH        Source config file  [required]
  -t, --to-file PATH          Output config file  [required]
  -y, --assume-yes            Assume yes for all prompts (default: False)
  --help                      Show this message and exit.
  
$ migrate-config smr  --help
Usage: migrate-config smr [OPTIONS]

  Migrate SMR config.

Options:
  -p, --migrate-path [v7-v9]  Migration path (choices: v7-v9)  [required]
  -f, --from-file PATH        Source config file  [required]
  -t, --to-file PATH          Output config file  [required]
  -y, --assume-yes            Assume yes for all prompts (default: False)
  --help                      Show this message and exit.

example output

Running migration function: migrate_v7_to_v9

Scanning node root configuration ...
`connection_refresh_timeout_sec = 2` is not recommended for new version.
Do you want to apply the recommended config: `connection_refresh_timeout_sec = 1`? (assuming yes)
✓ Apply recommended config: `connection_refresh_timeout_sec = 1`

Scanning ledger configuration ...
✓ `enable_pruning` not found in original config, using new version's default value: True
✓ `enable_snapshots` not found in original config, using new version's default value: False

Scanning chain store configuration ...
✓ `enable_snapshots` not found in original config, using new version's default value: False

Scanning prune configuration ...

Scanning mempool configuration ...
`max_batch_delay_ms = 1500` is not recommended for new version.
Do you want to apply the recommended config: `max_batch_delay_ms = 500`? (assuming yes)
✓ Apply recommended config: `max_batch_delay_ms = 500`

Scanning moonshot configuration ...
`message_recency_bound_rounds = 20` is not recommended for new version.
Do you want to apply the recommended config: `message_recency_bound_rounds = 1000`? (assuming yes)
✓ Apply recommended config: `message_recency_bound_rounds = 1000`
`sync_retry_delay_ms = 2000` is not recommended for new version.
Do you want to apply the recommended config: `sync_retry_delay_ms = 1000`? (assuming yes)
✓ Apply recommended config: `sync_retry_delay_ms = 1000`
`timeout_delay_ms = 5000` is not recommended for new version.
Do you want to apply the recommended config: `timeout_delay_ms = 3500`? (assuming yes)
✓ Apply recommended config: `timeout_delay_ms = 3500`
Writing new config to /tmp/new_smr.toml
|----------------- Begin diff v7 to v9 -----------------|

..
|----------------- End diff v7 to v9 -----------------|

    ######################################################################
    # Config migrated from tests/smr_settings_v7.1.x.toml to /tmp/new_smr.toml.
    # 
    # Please review the diff above for changes made during migration.
    # 
    # Please ensure to use the new config file for target binary version.
    ######################################################################

E2e migration process from v7 to v9 example script

Note that below scripts are example, should be adapted and not directly used

see node_management/migrate_config_and_db_mainnet_v7_to_v9.sh is example to be used for our foundation node to migrate config and db
see node_management/migrate_config_v7_to_v9_docker.sh is example to be used for migrate config only for node using docker.

node_management/migration/src/smr_settings/from_v7_to_v9.py

node_management/migration/src/smr_settings/migrate_path.py

node_management/migration/src/rpc_config/migrate_path.py

node_management/migration/src/rpc_config/from_v8_to_v9.py

node_management/migration/.gitignore

isaacdoidge · 2025-05-23T04:19:41Z

node_management/migration/README.md

+
+### Usage Example
+
+alias rpc-v8=~/Documents/share/repo/smr-moonshot-testnet/target/devopt/rpc_node


The node operators use Docker.

en.. I am thinking operator guide will be on web page not here. We can update the example here but need to have both native and docker one

node_management/migration/README.md

…plate Sc/upgrade config template

support dump template to toml file in cli

node_management/config_migration/README.md

isaacdoidge · 2025-06-04T10:19:19Z

node_management/config_migration/src/rpc_config/rpc_config_v9_1_x_mainnet_template.toml

+path = "./configs/rpc_archive"
+# Whether the database should be pruned. If `true`, data that is more than `epochs_to_retain`
+# old will be deleted.
+enable_pruning = false


As I mentioned in my comment on the readme, I now think we should set this to true for all databases on both nodes.

our archive rpc should not set it to true, it needs to be careful when using --assume-yes
we can set default to true, and have devops be aware of when migrating archive rpc it should be kept as false,

Good point. How do you suggest that we ensure the operators activate it then? Tell them not to update the value manually in the release docs?

Operator should always run in prompt mode. Because operator may want to run rpc as an archive.
Also I agree it is better to set default to true if the prune function is ready now for rpc. The validator template is already set to true. The update to rpc is done in a496619

It is easier to communicate to our devops than to operator, so ok to change it default to true, while I need to ask devops to always run migration-config manually for special denoted nodes (i.e. archive)
Similarly, as enable_snapshot default to false, also need to tell devops to not using assume-yes for snapshot uploader nodes

node_management/config_migration/src/rpc_config/rpc_config_v9_1_x_mainnet_template.toml

node_management/config_migration/src/smr_settings/smr_settings_v9_1_x_mainnet_template.toml

node_management/config_migration/tests/test_rpc_migration.py

isaacdoidge · 2025-06-04T10:26:24Z

node_management/manage_supra_nodes.sh

@@ -615,6 +615,12 @@ EOF
    if [ "$NETWORK" == "mainnet" ]; then
        export AWS_ACCESS_KEY_ID="c64bed98a85ccd3197169bf7363ce94f"
        export AWS_SECRET_ACCESS_KEY="0b7f15dbeef4ebe871ee8ce483e3fc8bab97be0da6a362b2c4d80f020cae9df7"
+
+        if is_validator; then


These buckets don't exist yet, so we can't make this update just yet. Both types of nodes need to default to the mainnet-data bucket for now.

I intended to put a palceholder, and then ask devops to create the bucket

Okay, but this script is currently regularly downloaded by the operators, so we won't be able to merge it until the new buckets are in place.

OK, that is fine, we can verify it work before merging

isaacdoidge · 2025-06-04T10:29:13Z

node_management/migrate_mainnet_from_v7_to_v9.sh

+    # Finished migration, and follow guide that start the node  with the new image with new config and sync
+    # ------
+
+    # ./manage_supra_nodes.sh \


Is this code still required?

I intended to keep it in case we need to create a script for operator case
i.e. migrate config only, then run sync

isaacdoidge · 2025-06-04T10:31:08Z

node_management/migrate_mainnet_from_v7_to_v9.sh

+    echo "Migrate cli profile from v8 to v9"
+    supra-v9 profile migrate
+    echo "Migrate smr_settings from v7 to v9"
+    # TODO(SC) to be run in docker context, update path to `./configs/config.toml`


Is this still WIP?

yes, because package of the migrate-config script into docker image is not yet ready

isaacdoidge · 2025-06-04T10:35:02Z

node_management/migrate_mainnet_from_v7_to_v9.sh

+    echo "Migrate db from v7 to v8"
+    rpc-v8 migrate-db configs/config.toml
+    echo "Migrate db from v8 to v9"
+    rpc-v9 migrate-db configs/config.toml


We don't want to run the v9 DB migration because it will take far too long. As with the testnet release, we'll run the migration ourselves, upload the snapshot and then ask the operators to download it.

This script is intended to be used by us, not by operator
in my mind, operator is guided by the user-guide to run migrate-config and sync manually.

the script was intended for us now, I thought we will provide user guide for operator to upgrade manually, if neded, we can create a new script for operator use case

We don't want to run this migration even on our own nodes. It takes 24+ hours. Syncing the snapshot takes maybe an hour.

We also don't use Docker on our machines.

We need to run it on a pair of rpc+validator snapshot uploader nodes, right?
I remember we had a few nodes running docker image also, or now it is completely native?
The docker image is only used for running migration, then removed, not for starting the nodes.
if the docker image is less performant to run migration, we can change it to use native build

We can also change the name of the script that is for supra devops for first step only. Then we can later create a script for operator use case

isaacdoidge · 2025-06-04T10:43:01Z

node_management/migrate_mainnet_from_v7_to_v9.sh

+    # Localnet only (Optional: local env path is different from docker env path, need to be modified to use docker env path)
+    sed -i "" "s#${HOST_SUPRA_HOME}#configs#g" ${HOST_SUPRA_HOME}/smr_settings.toml
+    echo "Migrate db from v7 to v9"
+    supra-v9 data migrate -p configs/smr_settings.toml


Let's not do this either. We'll migrate the database of one of our validators, then upload a snapshot for the operators to sync from. I'm concerned that anyone who has synced the snapshot in mainnet will end up having to migrate the full history of the chain store due to the RPC node's version of the database not having any entries in the prune index for historical values.

as explained in above about script purpose

Same response. Migrating will take too long if the full database has to be migrated.

I guess it is the name of the script make confusing, or the script should not be put in this repo.
the script was intended used for upgrading the snapshot uploaders nodes, not for all nodes. We can add a script for operator use case, and test on a pair of rpc+validator on mainnet after snapshot uploaders are done.
after that, then we can provide the verified operator specific script to operators

…1_x_mainnet_template.toml Co-authored-by: Isaac Doidge <[email protected]>

so-schen added 12 commits May 21, 2025 16:12

rpc config migration v7 to v8

ed3c6dc

rpc config migration v7 to v8

bdc4e3c

show diff after migration

8af24f4

packaging script

bf02ca3

support migrate path choices

5367ec0

support migrate path choices

ce4392a

support migrate path choices

9e2d0e3

add pytest to check diff

714fbce

improve ux

d882201

restore v7.1.8 template

9f0d675

update cli help ui

f1aa83d

add readme

e37634f

so-schen requested a review from isaacdoidge May 22, 2025 08:39

so-schen added 3 commits May 22, 2025 20:08

add migrate smrsetting

711bbd2

refactor

67c8501

update readme

b4cc37e

isaacdoidge reviewed May 23, 2025

View reviewed changes

so-schen added 13 commits May 23, 2025 15:17

address comments

b221ad3

prepare v9 mainnet rpc config template

710b4df

prepare v9 mainnet smr settings template

21e08af

update docs

8bd12e8

update docs

1ecfe57

migrate to v9 using templating

ce726ac

migrate to smr settings v9 using templating

f79fe03

update readme

b20842f

Merge pull request #670 from Entropy-Foundation/sc/upgrade-config-tem…

58ef54f

…plate Sc/upgrade config template

support dump template to toml file in cli

fa0774a

wip: packaing toml file

1007cb1

package toml in pip, impl scan updates

700e56d

fmt

5161f9e

so-schen added 3 commits May 28, 2025 19:17

scanning all parmaeters

0a2c4b6

Merge pull request #671 from Entropy-Foundation/sc/script-integration

17d501f

support dump template to toml file in cli

add docs

1f7af5b

so-schen requested review from sjadiya-supra and vpanchal-supra May 29, 2025 08:35

so-schen changed the title ~~Sc/upgrade test~~ Sc/config migration script for v7 to v9 May 29, 2025

so-schen changed the title ~~Sc/config migration script for v7 to v9~~ v7 to v9 config migration script May 29, 2025

so-schen added 8 commits May 29, 2025 10:41

update readme example

f884b17

rename dir

b1d2091

add back

9c7f76a

add

4ba2e84

update docs

5d366dc

update err handling

1fc2cb9

update docs

1dc5842

add docs and print

829f5e5

so-schen requested a review from ninad-supraoracles June 4, 2025 07:31

isaacdoidge reviewed Jun 4, 2025

View reviewed changes

so-schen and others added 4 commits June 4, 2025 13:43

Update node_management/config_migration/src/rpc_config/rpc_config_v9_…

5bc69c7

…1_x_mainnet_template.toml Co-authored-by: Isaac Doidge <[email protected]>

chore: remove codes

db185ea

address comments

db87a3b

enable_pruning = true for rpc

a496619

so-schen requested review from darpan-supraoracles and removed request for ninad-supraoracles June 5, 2025 07:02

so-schen added 3 commits June 5, 2025 09:47

add config only migration script for operator

7f1330e

keep originl value in chain instance

3f7c5ec

fix test

72be37d


		### Usage Example

		alias rpc-v8=~/Documents/share/repo/smr-moonshot-testnet/target/devopt/rpc_node

v7 to v9 config migration script #669

Are you sure you want to change the base?

v7 to v9 config migration script #669

Uh oh!

Conversation

so-schen commented May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Requirements

v7-v9 config migration docs

Install the config migration script

Usage

example output

E2e migration process from v7 to v9 example script

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

so-schen May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

so-schen Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

so-schen Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isaacdoidge Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

so-schen Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

so-schen Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

so-schen commented May 22, 2025 •

edited

Loading

so-schen May 23, 2025 •

edited

Loading

so-schen Jun 4, 2025 •

edited

Loading

so-schen Jun 4, 2025 •

edited

Loading

isaacdoidge Jun 4, 2025 •

edited

Loading

so-schen Jun 4, 2025 •

edited

Loading

so-schen Jun 4, 2025 •

edited

Loading

so-schen Jun 4, 2025 •

edited

Loading